<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>sendto</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4>NAME</h4><blockquote>
sendto - send a message on a socket
</blockquote><h4>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="syssocket.h.html">sys/socket.h</a>&gt;

ssize_t sendto(int <I>socket</I>, const void *<I>message</I>, size_t <I>length</I>, int <I>flags</I>,
      const struct sockaddr *<I>dest_addr</I>, socklen_t <I>dest_len</I>);
</code>
</pre>
</blockquote><h4>DESCRIPTION</h4><blockquote>
The
<i>sendto()</i>
function sends a message through a connection-mode or connectionless-mode
socket.  If the socket is connectionless-mode, the message will be sent to the
address specified by <I>dest_addr</I>.  If the socket is connection-mode,
<I>dest_addr</I> is ignored.
<p>
The function takes the following arguments:
<dl compact>

<dt><I>socket</I><dd>Specifies the socket file descriptor.

<dt><I>message</I><dd>Points to a buffer containing the message to be sent.

<dt><I>length</I><dd>Specifies the size of the message in bytes.

<dt><I>flags</I><dd>Specifies the type of message transmission.
Values of this argument are formed by logically OR'ing
zero or more of the following flags:
<dl compact>

<dt>MSG_EOR<dd>Terminates a record (if supported by the protocol)

<dt>MSG_OOB<dd>Sends out-of-band data on sockets that support out-of-band data.
The significance and semantics of out-of-band data are protocol-specific.

</dl>
<p>
<dt><I>dest_addr</I><dd>Points to a <B>sockaddr</B> structure containing the destination address.  The
length and format of the address depend on the address family of the socket.
<p>
<dt><I>dest_len</I><dd>Specifies the length of the <B>sockaddr</B> structure
pointed to by the <I>dest_addr</I> argument.
<p>
</dl>
<p>
If the socket protocol supports broadcast and the specified address
is a broadcast address for the socket protocol,
<i>sendto()</i>
will fail if the SO_BROADCAST option is not set for the socket.
<p>
The <I>dest_addr</I> argument specifies the address of the target.
The <I>length</I> argument specifies the length of the message.
<p>
Successful completion of a call to
<i>sendto()</i>
does not guarantee delivery of the message.
A return value of -1 indicates only locally-detected errors.
<p>
If space is not available at the sending socket to hold
the message to be transmitted and the socket file descriptor does not have
O_NONBLOCK set,
<i>sendto()</i>
blocks until space
is available.
If space is not available at the sending socket to hold
the message to be transmitted and the socket file descriptor does have
O_NONBLOCK set,
<i>sendto()</i>
will fail.
<p>
The socket in use may require the process to have appropriate
privileges to use the
<i>sendto()</i>
function.
</blockquote><h4>RETURN VALUE</h4><blockquote>
Upon successful completion,
<i>sendto()</i>
returns the number of bytes sent.  Otherwise, -1 is
returned and <I>errno</I> is set to indicate the error.
</blockquote><h4>ERRORS</h4><blockquote>
The
<i>sendto()</i>
function will fail if:
<dl compact>

<dt>[EAFNOSUPPORT]<dd>Addresses in the specified address family cannot be used with this socket.

<dt>[EAGAIN] or [EWOULDBLOCK]<dd><br>
The socket's file descriptor is marked O_NONBLOCK and the requested operation
would block.

<dt>[EBADF]<dd>The <I>socket</I> argument is not a valid file descriptor.

<dt>[ECONNRESET]<dd>A connection was forcibly closed by a peer.

<dt>[EFAULT]<dd>The 
<I>message</I>
or 
<I>destaddr</I>
parameter can not be accessed.

<dt>[EINTR]<dd>A signal interrupted
<i>sendto()</i>
before any data was transmitted.

<dt>[EMSGSIZE]<dd>The message is too large to be sent all at once, as the socket requires.

<dt>[ENOTCONN]<dd>The socket is connection-mode but is not connected.

<dt>[ENOTSOCK]<dd>The <I>socket</I> argument does not refer to a socket.

<dt>[EOPNOTSUPP]<dd>The <I>socket</I> argument is associated with a socket that does not
support one or more of the values set in <I>flags</I>.

<dt>[EPIPE]<dd>The socket is shut down for writing, or the socket is
connection-mode and is no longer connected.
In the latter case, and if the socket is of type SOCK_STREAM, the SIGPIPE
signal is generated to the calling process.

</dl>
<p>
If the address family of the socket is AF_UNIX, then
<i>sendto()</i>
will fail if:
<dl compact>

<dt>[EIO]<dd>An I/O error occurred while reading from or writing to the file system.

<dt>[ELOOP]<dd>Too many symbolic links were encountered in translating the pathname in the
socket address.

<dt>[ENAMETOOLONG]<dd>A component of a pathname exceeded {NAME_MAX} characters, or an entire
pathname exceeded {PATH_MAX} characters.

<dt>[ENOENT]<dd>A component of the pathname does not name an existing file or the pathname is
an empty string.

<dt>[ENOTDIR]<dd>A component of the path prefix of the pathname in the socket address is not a
directory.

</dl>
<p>
The
<i>sendto()</i>
function may fail if:
<dl compact>

<dt>[EACCES]<dd>Search permission is denied for a component of the path prefix;
or write access to the named socket is denied.

<dt>[EDESTADDRREQ]<dd>The socket is not connection-mode and does not have its peer address set,
and no destination address was specified.

<dt>[EHOSTUNREACH]<dd>The destination host cannot be reached (probably because the host is down or
a remote router cannot reach it).

<dt>[EINVAL]<dd>The <I>dest_len</I> argument is not a valid length for the address family.

<dt>[EIO]<dd>An I/O error occurred while reading from or writing to the file system.

<dt>[EISCONN]<dd>A destination address was specified and the socket
is already connected.

<dt>[ENETDOWN]<dd>The local interface used to reach the destination is down.

<dt>[ENETUNREACH]<dd>No route to the network is present.

<dt>[ENOBUFS]<dd>Insufficient resources were available in the system to perform the operation.

<dt>[ENOMEM]<dd>Insufficient memory was available to fulfill the request.

<dt>[ENOSR]<dd>There were insufficient STREAMS resources available for the operation to
complete.

</dl>
<p>
If the address family of the socket is AF_UNIX, then
<i>sendto()</i>
may fail if:
<dl compact>

<dt>[ENAMETOOLONG]<dd>Pathname resolution of a symbolic link produced an intermediate result whose
length exceeds {PATH_MAX}.

</dl>
</blockquote><h4>APPLICATION USAGE</h4><blockquote>
The
<i><a href="select.html">select()</a></i>
and
<i><a href="poll.html">poll()</a></i>
functions can be used to determine when it is possible to send more data.
</blockquote><h4>SEE ALSO</h4><blockquote>
<i><a href="getsockopt.html">getsockopt()</a></i>,
<i><a href="poll.html">poll()</a></i>,
<i><a href="recv.html">recv()</a></i>,
<i><a href="recvfrom.html">recvfrom()</a></i>,
<i><a href="recvmsg.html">recvmsg()</a></i>,
<i><a href="select.html">select()</a></i>,
<i><a href="send.html">send()</a></i>,
<i><a href="sendmsg.html">sendmsg()</a></i>,
<i><a href="setsockopt.html">setsockopt()</a></i>,
<i><a href="shutdown.html">shutdown()</a></i>,
<i><a href="socket.html">socket()</a></i>,
<i><a href="syssocket.h.html">&lt;sys/socket.h&gt;</a></i>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
